______________________________________________________________________ Browser Toolkit Library Reference - BSCREF.TXT Microsoft Visual C++ Browser Toolkit for Windows NT (C) Copyright Microsoft Corporation, 1993 This document discusses the Microsoft Visual C++ Browser Toolkit API definitions. It explains how to use the browser library to access the contents of a browser database. Contents 1 Using the Browser Library 1.1 Compiling Programs 2. Browser Database Functions 2.1 Callback Functions 2.2 Opening and Closing a Browser Database 2.3 Database Index Variables 2.3.1 Modules (IMOD Variables) 2.3.2 Module Symbols (IMS Variables) 2.3.3 Symbols (ISYM Variables) 2.3.4 Symbol Instances (IINST Variables) 2.3.5 Definitions and References (IDEF and IREF Variables) 2.3.6 Uses/Used-by Information (IUSE and IUBY Variables) 2.3.7 Base and Derived Classes (IBASE and IDERV Variables) 2.3.8 Friend (In/Out) Classes (IFRIN and IFROUT Variables) 2.4 Generating Calltrees and Classtrees 2.4.1 Sample Calltrees 2.4.2 Sample Classtrees 2.5 Listing Database References 2.6 File Outline Functions 2.7 String Processing Functions 2.8 Miscellaneous Functions 3. Browser Objects 3.1 Creating and Manipulating BOB Variables 3.2 Performing Database Queries 3.3 Generating Name Overloads 4. Browser Library Index ______________________________________________________________________ 1 Using the Browser Library The Browser Toolkit includes a powerful library of functions that give you complete access to browser database files created by Microsoft Visual C++. This browser library, named BSC.LIB, contains functions that access browser database files (.BSC), query database tables, and even generate information, such as calltrees and symbol reference tables. Additionally, BSC.LIB incorporates functions that access and manipulate information about C++ classes and objects that may be present in a browser database. For example, some of these functions create classtrees and return undecorated names of C++ functions (typically stored in decorated form). To provide BSC.LIB users maximum flexibility, the Browser Toolkit allows you to implement several callback functions described below (see section 2.1). A callback function is one that performs a particular system service required by the browser library. Some examples of such services are memory allocation, file I/O, and error-handling. The BSC.LIB file provides callbacks so that the browser library does not have to depend on the run-time library for these services. Instead, library functions "call back" to the function designated to perform a particular service without the library requiring any knowledge of how this service is performed. Because you have the option of writing your own callbacks, these functions provide a flexible interface to any environment that might require special access to run-time resources. ______________________________________________________________________ 1.1 Compiling Programs To compile a browser program (such as the BSCDUMP.C program used in this example) and link it with BSC.LIB at the MS-DOS prompt, you can use the following command: cl -W3 -I. bscdump.c bsc.lib -link -nodefaultlib:libcmt.lib -defaultlib:libc.lib NOTE: If you choose to define the callbacks (described in the following section) required by the library, they will not be linked from BSC.LIB. Defining these callbacks yourself allows BSC.LIB to be used in any custom environments you may have (such as Windows real mode, for example). Be sure to link with the appropriate file(s) containing your callback definitions ______________________________________________________________________ 2 Browser Database Functions The following sections describe various browser database functions. ______________________________________________________________________ 2.1 Callback Functions The BSC.LIB file provides default versions of all callback functions. These defaults should provide you with the necessary flexibility to develop programs for most environments. However, if an environment does not permit the use of normal run-time calls, you must define several callback functions to avoid dependency on the C standard I/O library. Table 2 outlines the prototypes for functions that handle basic I/O and memory allocation and deallocation. If you implement these functions yourself, ensure that your versions follow the specifications described below. Table 2: Callback Functions ------------------------------------------------------------ Callback To Prototype Result ------------------------------------------------------------ Standard LPV BSC_API LpvAllocCb( A void far memory WORD cb) pointer must be allocation returned to a function block of size cb bytes. If the block of memory has not been allocated, then the return value should be NULL. Standard VOID BSC_API FreeLpv( Given a void far memory LPV lpv) pointer to a deallocatio block of memory n function lpv, the function must deallocate the memory block. Standard int BSC_API BSCOpen( Opens the file file open LSZ lszFileName, lszFileName and function int mode) prepares the file for subsequent reading or writing, as defined by mode. The function must return a file handle for the opened file. A return value of -1 should indicate an error. The mode parameter may be any combination of the O_* bits that are used in the standard open() call. At this time, however, the library will make this call only with mode = O_BINARY | O_RDONLY. Standard int BSC_API BSCClose( Closes the file file close int handle) with the given function handle value. A return of 0 should indicate success. Standard int BSC_API BSCRead( Reads a number file read int handle, of bytes ch from function LPCH lpchBuf, the file with WORD ch) the given handle into the far character buffer pointed to by lpchBuf. The return value should be the number of actual bytes that were read, or -1 if an error occurred. Standard int BSC_API BSCSeek( Moves the file file seek int handle, pointer function long lPos, associated with int mode) the file with the given handle to a new location, lpos bytes from the position in the file determined by mode. Here, mode can be any of SEEK_CUR, SEEK_END, or SEEK_SET as in the lseek() call from the C standard library. Currently, only SEEK_SET is used by BSC.LIB. The return value should be -1 on an error; any other value indicates success. ASCII text VOID BSC_API BSCOutput( Writes the given output LSZ lsz) zero-terminated function string to the standard output. This function is called by the library whenever it wants to output any text (that is, for a calltree or classtree, outline, or other request). The default implementation writes to the standard output; however, a user implementation of this function can direct the output elsewhere. Error- VOID BSC_API SeekError( These functions handling LSZ LszFilename) should be functions provided to handle the VOID BSC_API ReadError( occurrence of LSZ LszFilename) any one of the corresponding errors. The VOID BSC_API BadBSCVer( string parameter LSZ LszFilename) is the name of the file involved in the error. If these functions choose to exit the application, they should close any file(s) the browser has opened. ______________________________________________________________________ 2.2 Opening and Closing a Browser Database Two browser library functions open and close a browser database file. The following table details the prototypes for these functions. Table 3: File Opening/Closing Functions ------------------------------------------------------------ Purpose Prototype Result ------------------------------------------------------------ Opens the BOOL BSC_API FOpenBSC Opens the .BSC file (LSZ lszName) specified database file lszName. Returns the value TRUE if successful, or FALSE if unsuccessful. The lszName parameter can be any valid path name to a .BSC file. Closes VOID BSC_API CloseBSC Closes the the .BSC (VOID) current database file file. This will free any memory the library may be using. ______________________________________________________________________ 2.3 Database Index Variables Each object found in the browser database is represented by a numerical index value that uniquely identifies one database object. The name of every index variable type begins with the letter "I" and ends with letters referring to the kind of object indexed by the variable. Each of these index variable types and the functions that operate on them are described below. 2.3.1 Modules (IMOD Variables) Each module in the database has an associated module index (IMOD) value. Using the functions detailed in the following table, you can convert a filename into a module index, convert a module index into a filename, or enumerate all the module index values in the database. Table 4: IMOD Conversion Functions ------------------------------------------------------------ Purpose Prototype Result ------------------------------------------------------------ Converts LSZ BSC_API LszNameFrMod LszNameFrMod from IMOD (IMOD imod) (given a to module module index name imod) returns the zero- terminated string name for that symbol index. Converts IMOD BSC_API ImodFrLsz ImodFrLsz from (LSZ lszModName) returns the module index, if one name to exists, from IMOD the symbol name lszModName. If that module name does not exist, then the return value is imodNil. Determine IMOD BSC_API ImodMac The return s largest (VOID) value is the IMOD biggest IMOD value index in this database; the range of these indexes is from zero to the return value less one. 2.3.2 Module Symbols (IMS Variables) The browser database contains a list of all the symbol instances (see section 2.3.4, Symbol Instances) defined in any particular module. These module symbols also are referenced via a module symbol index (called an IMS value). Given a module index (IMOD) variable, certain library functions can find the range of valid module symbol index (IMS) values for that module. This range of values then can be used to reveal the contents of that module. Table 5 describes functions that either operate on or return IMS values. Table 5: IMS Values ------------------------------------------------------------ Purpose Prototype Result ------------------------------------------------------------ Determines VOID BSC_API MsRangeOfMod( The IMS values the range IMOD imod, pointed to by of IMS IMS far *pimsMin, pimsMin and values for IMS far *pimsMac) pimsMac will the given contain the IMOD IMS start and end values for the specified module index. If pimsMin is equal to pimsMac, then the specified module (imod) contains no definitions and hence has no corresponding IMS values. Gets the IINST BSC_API IinstOfIms( Given the instance IMS ims) index ims of a index module symbol, (IINST) this function from the returns the module instance index symbol for subsequent index (IMS) use in other calls. Refer to section 2.3.4 for a discussion of symbol instances. 2.3.3 Symbols (ISYM Variables) All symbols (identifiers) of any type have an associated symbol index (ISYM); that is, there is a one- to-one correspondence between symbol indexes and symbol names known to the database. The range of valid symbol index values is determined by the call ISYM BSC_API IsymMac (VOID) which determines the size of a browser database's symbol table. The return value is the biggest symbol index in the particular browser database being queried. The range of valid indexes is from zero to the return value less one. Symbol index values are assigned to symbols in alphabetical order (with one exception: a leading question mark in decorated names is ignored). For example, to obtain a list of symbols in sorted order, you need only obtain the text of symbols with ISYM values of 0, 1, 2 , 3, and so forth, up to the value returned by IsymMac less one. Another library function determines the smallest symbol index whose value is greater than or equal to that of a given symbol name. ISYM BSC_API IsymSupLsz (LSZ lszSymName) Strings can be converted to symbol indexes (and vice versa) using the following calls: LSZ BSC_API LszNameFrSym (ISYM isym) ISYM BSC_API IsymFrLsz (LSZ lszSymName) Given an index isym, LszNameFrSym returns the zero- terminated string name for the symbol index. IsymFrLsz returns the index, if one exists, from the symbol name lszSymName. If that symbol name does not exist in the database, the function returns isymNil. To get data other than the name from a symbol index, you must enumerate its corresponding instance values, which correspond to the various instances of that symbol. These instance values are discussed next. 2.3.4 Symbol Instances (IINST Variables) Every symbol in a browser database is associated with several instances, each of which corresponds to a different way the symbol is used in the program(s) described in the browser database (see Table 6). For example, the symbol "mysymbol" might be used as a static variable in one place, and as a function parameter in another. The browser library keeps track of these various instances using instance index values called IINST variables. Table 6: IINST Values ------------------------------------------------------------ Purpose Prototype Result ------------------------------------------------------------ Determines VOID BSC_API Fills in the the range InstRangeOfSym ( values of of valid ISYM isym, piinstMin and IINST IINST far *piinstMin, piinstMac in an values for IINST far *piinstMac) analogous way to a MsRangeOfMod() particular described in symbol Table 5. (isym) Finds the IINST BSC_API IinstMac ( As with range of VOID) ImodMac() and valid IsymMac(), IINST IinstMac returns values for the upper bound the whole on valid IINST database values. IINST values range from zero to the return value less one. Retrieves VOID BSC_API InstInfo ( Fills in the information IINST iinst, corresponding about a ISYM far *pisyminst, symbol, type, particular TYP far *ptype, and attribute instance ATR far *pattr) values (pointer to ISYM, TYP, and ATR, respect- ively) given an IINST. ISYM values are discussed in section 2.3.3. Finds the IINST IinstContextFrIref( Returns the IINST IREF iref) IINST value for value that the instance best that best represents represents the the context context at the at the reference location indicated by the of the given iref. If given IREF. it finds no such For instance index, example, if the function you have an returns IREF for iinstNil. IREF some variables are variable, discussed in the context section 2.3.5. IINST would This function be the uses a function heuristic, "best that the guess" algorithm variable that is highly was defined accurate, though in. not 100% so. Finds the IINST IinstFrIref ( Returns the IINST IREF iref) IINST value for which the instance contains that contains the given the reference IREF. indicated by iref. If it finds no such instance index, the function returns iinstNil. This function will fail if iref is an invalid reference index. IREF variables are discussed in section 2.3.5. Finds the IINST IinstFrIdef ( Returns the IINST IDEF idef) IINST value for which the instance contains that contains the given the definition IDEF. indicated by idef. If it finds no such instance index, the function returns iinstNil. This function will fail if idef is an invalid definition index. IDEF variables are discussed in section 2.3.5. The type value (refer to InstInfo in Table 6) will be exactly one of the following: INST_TYP_FUNCTION INST_TYP_LABEL INST_TYP_PARAMETER INST_TYP_VARIABLE INST_TYP_CONSTANT INST_TYP_MACRO INST_TYP_TYPEDEF INST_TYP_STRUCNAM INST_TYP_ENUMNAM INST_TYP_ENUMMEM IINST_TYP_UNIONNAM INST_TYP_SEGMENT INST_TYP_GROUP INST_TYP_PROGRAM INST_TYP_CLASSNAM INST_TYP_MEMFUNC INST_TYP_MEMVAR Note that three of these constants refer to C++ symbols: INST_TYP_CLASSNAM, INST_TYP_MEMFUNC, and INST_TYP_MEMVAR. The attribute value describes the storage class and/or scope of the instance. Any combination of the attribute bits may be set, although some combinations do not make sense and thus do not occur in practice. These bits can be tested using the C/C++ languages' bitwise operators, or through the use of the FInstFilter function (described in Table 7). The attribute bits are as follows: INST_ATR_LOCAL INST_ATR_STATIC INST_ATR_SHARED INST_ATR_NEAR INST_ATR_COMMON INST_ATR_DECL_ONLY INST_ATR_PUBLIC INST_ATR_NAMED INST_ATR_MODULE INST_ATR_VIRTUAL INST_ATR_PRIVATE INST_ATR_PROTECT Additionally, for inheritance mode attributes, the following constants have been defined: IMODE_VIRTUAL IMODE_PRIVATE IMODE_PUBLIC IMODE_PROTECT Several functions designed to help with some typical operations on instance index values are shown in Table 7. Table 7: Attribute-Testing Functions ------------------------------------------------------------ Purpose Prototype Result ------------------------------------------------------------ Acts as an BOOL BSC_API FInstFilter ( FInstFilter attribute IINST iinst, returns TRUE if filter MBF mbf) the given IINST value has a TYP value that corresponds with the value passed in mbf. See the list of possible MBF values below this table. Gets an LSZ BSC_API LszTypInst ( Returns the ASCII IINST iinst) zero-terminated version of ASCII string an IINST from the variable instance index type iinst. These correlate directly with the types given above as INST_TYP_LABEL and so on. Dumps a VOID BSC_API DumpInst ( Outputs single IINST iinst) information instance about the instance indexed by iinst to the standard output using the BSCOutput() callback. The format of the output is described below. FInstFilter requires an instance type filter as one of its parameters. The instance type (called an MBF) can be any bitwise-OR combination of the following constants: mbfNil mbfVars mbfFuncs mbfMacros mbfTypes mbfClass mbfAll The instance information output provided by DumpInst has the following format: 2.3.5 Definitions and References (IDEF and IREF Variables) Each instance in the database has an associated set of definitions and references, which also are tracked using index variables (IDEF and IREF). The two functions below return the range of valid definition and reference index values for a given instance. VOID BSC_API DefRangeOfInst (IINST iinst, IDEF far *pidefMin, IDEF far *pidefMac) VOID BSC_API RefRangeOfInst (IINST iinst, IREF far *pirefMin, IREF far *pirefMac) The first of these functions returns index limits in two IDEF variables; the second returns the limits in IREF variables. From a definition or reference index, the actual filename and line number of a particular instance reference or definition can be determined using one of the following functions: VOID BSC_API DefInfo (IDEF idef, LSZ far *plszName, WORD far *pline) VOID BSC_API RefInfo (IDEF iref, LSZ far *plszName, WORD far *pline) NOTE: Study the prototype for these two functions carefully. The LSZ argument is handled in an atypical way. Instead of placing text in a buffer that the caller provides, the library actually fills in a pointer to one of its internal buffers where the filename can be found. The LSZ pointer is set to point to this buffer. If you intend to use the contents of this buffer after making another call to the library, be sure to copy these contents, or they may be lost in the next library call. 2.3.6 Uses/Used-by Information (IUSE and IUBY Variables) Each symbol in the database has an associated set of instances that use the given symbol or that the symbol uses. These "uses" and "used-by" instances have associated index variables called IUSE and IUBY, respectively. For a particular instance, these uses/used-by instances can be accessed by first determining the range of valid uses/used-by index values via one of the following functions: VOID BSC_API UseRangeOfInst (IINST iinst, IUSE far *piuseMin, IUSE far *piuseMac) VOID BSC_API UbyRangeOfInst (IINST iinst, IUBY far *piubyMin, IUBY far *piubyMac) From a "uses" or "used-by" instance index, the corresponding instance that uses or is used by the queried instance can be found, as can the number of times such use occurs. VOID BSC_API UseInfo (IUSE iuse, IINST far *piinst, WORD far *pcnt) VOID BSC_API UbyInfo (IUBY iuby, IINST far *piinst, WORD far *pcnt) After a call to one of the above functions, piinst will point to the instance index (IINST) value for the instance to which the IUSE or IUBY variable refers. The pcnt variable will point to the number of times the respective use occurs. 2.3.7 Base and Derived Classes (IBASE and IDERV Variables) Some instances in the browser database could refer to classes that they are based on or from which they are derived. In similar form to other index-range functions, two library functions provide the valid base class or derived class index range: VOID BSC_API BaseRangeOfInst (IINST iinst, IBASE far *pibaseMin, IBASE far *pibaseMac) VOID BSC_API DervRangeOfInst (IINST iinst, IDERV far *pidervMin, IDERV far *pidervMac) If an instance does not represent a class, then the Min/Mac pointers will point to the same value. Given an index to a base, you can obtain information about the base or derived classes using the following functions: VOID BSC_API BaseInfo(IBASE ibase, IINST far *piinst, WORD far *pmode) VOID BSC_API DervInfo(IDERV iderv, IINST far *piinst, WORD far *pmode) For a given IBASE or IDERV index, these functions return the instance for the base/derived class and the inheritance mode. 2.3.8 Friend (Incoming/Outgoing) Classes (IFRIN and IFROUT Variables) Assume that your code has a class named A. An incoming friend of class A is a class that gives class A friend access. An outgoing friend of class A is a class that obtains friend access from class A. Note that it is possible for a function to have incoming friends but no outgoing friends (that is, a function can be given friend access, but the function does not give such access). For each type of friend, index variables (either IFRIN or IFROUT) track all friend instances. For a particular instance, there may be several other instances that give or obtain friend access to or from other instances. Given an instance index, the following functions return the valid range of friend indexes for that instance: VOID BSC_API FrinRangeOfInst(IINST iinst, IFRIN far *pifrinMin, IFRIN far *pifrinMac) VOID BSC_API FroutRangeOfInst(IINST iinst, IFROUT far *pifroutMin, IFROUT far *pifroutMac) Given a single friend index (either incoming or outgoing), the following functions return the instance of the corresponding friend: VOID BSC_API FrinInfo(IFRIN ifrin, IINST far *piinst) VOID BSC_API FroutInfo(IFROUT ifrout, IINST far *piinst) ______________________________________________________________________ 2.4 Generating Calltrees and Classtrees A very important feature of the browser database is the ability to generate calltrees from any function and classtrees from any C++ class instance or name. These trees may be generated in both forward and backward directions from the given instance index or symbol name. The following functions generate the calltree or classtree from either an instance index or a symbol name, respectively: Calltrees: VOID BSC_API CallTreeInst (IINST iinst) VOID BSC_API RevTreeInst (IINST iinst) VOID BSC_API FCallTreeLsz (LSZ lszName) VOID BSC_API FRevTreeLsz (LSZ lszName) Classtrees: VOID BSC_API ClassTreeInst (IINST iinst) VOID BSC_API RevClassTreeInst (IINST iinst) VOID BSC_API FRevClassTreeLsz (LSZ lszname) VOID BSC_API FClassTreeLsz (LSZ lszname) For calltrees, the symbol name may be either the name of a function or the name of a module. In the latter case, the root of the tree is the module name; the child subtrees are the functions contained in that module. For classtrees, the symbol name may be the name of a function, variable, or class. The result is ASCII text output to the standard output. Indentations denote different levels of the tree. If any node is visited more than once, due to cycles in the call graph, then the node's name will be succeeded by an ellipsis (...). If the source script of the function is not known, then it will be followed by a question mark (?). The following is sample source code that will be used to demonstrate the output of these and, in subsequent sections, other functions. #include void one (void); void two (void); void three (void); void five (void); void one() { printf("One, "); } void two() { printf("Two, "); three(); five(); } void three() { printf("Three, "); } void five() { printf("Five\n"); } main() { printf("This program prints the first "); printf("five Fibonacci numbers . . .\n"); one(); one(); two(); } 2.4.1 Sample Calltrees The following are five separate forward calltrees for the symbols main, one, two, three, and five from the source script listed above: main one two three five |__printf[2]? |__printf? |__printf? |__printf? |__printf? |__one[2] |__three | |__printf? | |__printf? |__two |__five |__printf? |__printf? |__three | |__printf? |__five |__printf? The two reverse calltrees listed below are for the symbols printf and five from the sample source: printf five |__one |__two | |__main[2] |__main |__two | |__main... |__three | |__two... |__five | |__two... |__main[2]... 2.4.2 Sample Classtrees The tree on the left is a forward classtree for the symbol CWnd from the HELLOAPP program provided with Visual C++ (see the MFC SAMPLES directory). The tree on the right is a reverse classtree for the symbol CHelloWindow from the same program. CWnd CHelloWindow |__CDialog |__CFrameWnd | |__CModalDialog |__CWnd |__CStatic |__CCmdTarget |__CButton |__CObject | |__CBitmapButton |__CObjectRoot |__CListBox |__CComboBox |__CEdit |__CScrollBar |__CFrameWnd | |__CMDIFrameWnd | |__CMDIChildWnd | |__CHelloWindow |__CView |__CScrollView ______________________________________________________________________ 2.5 Listing Database References The following function, ListRefs, lists references of all symbols in the browser database which meet the requirements set by the filter mask mbfReqd. These symbols will be dumped to the standard output. If the function is unable to complete its task, then the return value is FALSE; otherwise it is TRUE. BOOL BSC_API ListRefs (MBF mbfReqd) The filter mask can be set using the bitwise OR operator, as in ListRefs (mbfFuncs | mbfMacros | mbfTypes) which produces the following output for the sample script listed above: FUNCTION CALLED BY LIST five: two main: one: main[2] printf: one two three five main[2] three: two two: main MACRO USED BY LIST _MSC_VER: TYPE USED BY LIST _iobuf: FILE: fpos_t: size_t: va_list: ______________________________________________________________________ 2.6 File Outline Functions The following function outputs an outline of a module: VOID BSC_API OutlineMod (IMOD imod, MBF mbf) Given a module symbol index imod and a filter mask mbf, this function sends to the standard output all of the symbols in that module with attributes and type that match the required filter. For example, a call of this fuction OutlineMod (imod, mbfVars | mbfFuncs) produces the following output: fib.c five (function:public) main (function:public) one (function:public) three (function:public) two (function:public) The following function outputs the outline for the module(s) matching a name or pattern: BOOL BSC_API FOutlineModuleLsz (LSZ lszName, MBF mbf) This function performs similarly to OutLineMod, except the zero-terminated string lszName may contain the pattern-matching wildcards * and ?. ______________________________________________________________________ 2.7 String Processing Functions Table 8 describes the operation of string processing functions. Table 8: String Processing Functions ------------------------------------------------------------ Action Prototype Result ------------------------------------------------------------ Simple VOID BSC_API BSCFormat ( Format from formatter LPCH lpchOut, the string LSZ lszFormat, lszFormat to va_list va) the string lpchOut as specified by the standard switch (for example, %s). Simple VOID BSC_API BSCPrintf ( Takes one or printf LSZ lszFormat, more zero- replacement ...) terminated strings and outputs them to the standard output. Only two switches are supported, %d and %s. Simple VOID BSC_API BSCSprintf ( See BSCPrintf sprintf LPCH lpchOut, above. replacement LSZ lszFormat, ...) Pattern- BOOL BSC_API FWildMatch ( Returns TRUE matching LSZ lszPat, if the pattern function LSZ lszText) string lszPat matches the string lszText. The standard wildcards (* and ?) may be used in the pattern string. Matching occurs just as MS-DOS matches filenames. Compares INT BSC_API CaseCmp ( Performs a strings LSZ lszl, case- LSZ lsz2) (in)sensitive comparison, depending on the current case sensitivity, which can be set by SetCaseBSC (see Table 9). The comparison occurs in the order of symbols listed in the symbol table. Compares int BSC_API CaseCmpPrefix ( Nearly prefixes LSZ lszprefix, identical to of two LSZ lszdecor) CaseCmp except strings that only the prefixes of two strings are compared. Returns LSZ BSC_API LszBaseName ( Given a path the base LSZ lsz) name lsz, the name of base name is a path extracted and returned. If an empty string is passed to the function, then the empty string is returned. Obtains LSZ BSC_API FormatDname ( Returns the undecora LSZ lszname) undecorated ted name for the names function name indicated by lszname. Returns LSZ BSC_API LszBaseOfDname Returns the the base (LSZ lszname) full name if name of lszname is a undecorated, decorate the member d name. name if lszname is a member variable or member function, the function or variable name if lszname is just a decorated function or data item (global), or the class name if lszname is a constructor or destructor. All other inputs return NULL. Returns LSZ BSC_API LszClassOfDname Returns the the (LSZ lszname) class name class from a name decorated name from a or NULL if decorate lszname d name. contains no class name. If lszname is either not decorated or if the class name part of a decorated lszname is empty (as in a global operator), then the pointer return is NULL. ______________________________________________________________________ 2.8 Miscellaneous Functions Table 9 describes other useful browser functions: Table 9: Miscellaneous Functions ------------------------------------------------------------ Purpose Prototype Result ------------------------------------------------------------ Assists WORD BSC_API BSCMaxSymLen Returns the formatting (VOID) length of the of output largest symbol from in the browser database database. queries Determines BOOL BSC_API FCaseBSC Returns TRUE if case (VOID) the database is sensitivity built with case- sensitive language; returns FALSE otherwise. Sets the VOID BSC_API SetCaseBSC Overrides the case (BOOL fCase-Sensitive) case sensitivity sensitivity of the database. Look-ups in the symbol table become case (in)sensitive as specified by fCaseSensitive. Dumps VOID BSC_API StatsBSC() Outputs database statistics to statistics the standard output using BSCOutput. As an example of the output from StatsBSC, consider the simple "Hello world!" script: #include main() { printf("Hello world!"); } For this script, StatsBSC produces the following: Totals MOD : 3 MODSYM : 13 SYM : 13 INST : 13 REF : 55 DEF : 13 USE : 6 UBY : 6 Detail Modsyms:2 C:\WINDEV\INCLUDE\stdio.h Modsyms:10 hello.c Modsyms:1 _base (mem_var:public) DEF 1 REF 0 USE 0 UBY 1 _cnt (mem_var:public) DEF 1 REF 0 USE 0 UBY 1 _file (mem_var:public) DEF 1 REF 0 USE 0 UBY 1 _flag (mem_var:public) DEF 1 REF 0 USE 0 UBY 1 _iobuf (struct_name) DEF 1 REF 1 USE 5 UBY 0 _MSC_VER (constant) DEF 1 REF 1 USE 0 UBY 0 _ptr (mem_var:public) DEF 1 REF 0 USE 0 UBY 1 FILE (typedef) DEF 1 REF 40 USE 0 UBY 0 fpos_t (typedef) DEF 1 REF 2 USE 0 UBY 0 main (function:public) DEF 1 REF 0 USE 1 UBY 0 printf (function:decl_only:public) DEF 1 REF 2 USE 0 UBY 1 size_t (typedef) DEF 1 REF 5 USE 0 UBY 0 va_list (typedef) DEF 1 REF 4 USE 0 UBY 0 ______________________________________________________________________ 3 Browser Objects The following sections describe browser objects (BOBs). ______________________________________________________________________ 3.1 Creating and Manipulating BOB Variables The browser library provides several high-level functions that help the client query the information stored in the database. Examples of such queries include: - Information about the names of all modules in the database - Functions an instance might call - Occurrences of a symbol definition - Friend access relationships All the queries process one item called a browser object (BOB). A browser object is actually one of the index values that are encoded along with the type of index into a 32-bit quantity. Thus, once it is known, the type or "class" of the browser object can be extracted, as can its appropriate index value (see below). The ClsOfBob() macro returns one of the following CLS (class) types for the given browser object: clsMod clsInst clsSym clsRef clsDef clsUse clsUby clsBase clsDerv clsFrin clsFrout A browser object can be created from either a name of a symbol known to the database or from an index which is valid with respect to the database. The following call creates a browser object from the name of the object: BOB BSC_API BobFrName (LSZ lsz) If no browser object can be created from the given name, the value bobNil is returned. If the name is found, then the browser object returned will be either of class clsMod (if the name was a module name) or of class clsInst (if the name was a symbol name). If more than one instance is associated with the given name, the browser object's value will be the first (smallest) such instance. The following macros can create a browser object from one of the index values. Listed beside each macro is the macro that performs the reverse operation. BobFrMod ( IMOD x ) ImodFrBob ( BOB b ) BobFrSym ( ISYM x ) IsymFrBob ( BOB b ) BobFrInst ( IINST x ) IinstFrBob ( BOB b ) BobFrRef ( IREF x ) IrefFrBob ( BOB b ) BobFrDef ( IDEF x ) IdefFrBob ( BOB b ) BobFrUse ( IUSE x ) IuseFrBob ( BOB b ) BobFrUby ( IUBY x ) IubyFrBob ( BOB b ) BobFrBase ( IBASE x ) IbaseFrBob ( BOB b ) BobFrDerv ( IDERV x ) IdervFrBob ( BOB b ) BobFrFrin ( IFRIN x ) IfrinFrBob ( BOB b ) BobFrFrout ( IFROUT x ) IfroutFrBob ( BOB b ) All of the macros on the left use the function BobFrClsIdx, which, given one of the indexes shown above, returns the appropriate BOB. NOTE: The macros that convert an index into a browser object create a BOB whose class type corresponds to the type of index given. But the macros that convert a browser object back to an index do not check to make sure that the browser object has the correct class type value to do the conversion. It is up to the user of these macros to do whatever checking may be required before using them. To retrieve the symbol name of a browser object, use the function LSZ BSC_API LszNameFrBob ( BOB bob ) which returns either a symbol name or a module name, depending on the class type of the browser object. The browser library also has a function that retrieves a range of symbol indexes given only a prefix. To obtain this range, use the function BOOL BSC_API FindPrefixRange ( LSZ lszprefix, ISYM far *pfirstisym, ISYM far *plastisym ) which returns TRUE if the search was successful, or FALSE otherwise. Matching for this function always is case insensitive. ______________________________________________________________________ 3.2 Performing Database Queries You can initiate several predefined queries once a browser object has been created. These are passed to the function InitBSCQuery along with the browser object itself. BOOL BSC_API InitBSCQuery (QY qy, BOB bob) The function returns TRUE if the query has been initiated successfully, FALSE otherwise. Not all queries can be performed on all browser objects (for example, trying to perform the query "What does this browser object call?" when the browser object type is actually that of a module index). The possible queries and their permitted browser object types are outlined in Table 10. Table 10: Database Queries and BOB Types ------------------------------------------------------------ Query Input Return Query initiated for BOB Type BOB Type ------------------------------------------------------------ qyFiles (ignored) module Modules that are defined in the database. qySymbols (ignored) instance Instances of symbols that occur in the database. qyContains module instance Symbols that are defined in that module. qyCalls instance instance Instances that a function (instance) calls. If the instance in that BOB is not of the type function, then the list of instances returned will be of zero length. qyUses instance instance Instances that an instance uses. qyCalledBy instance instance Instances that call the input instance. These instances will be of the type function. qyUsedBy instance instance Instances that use the input instance. qyUsedIn instance module Module(s) that use/reference the instance. qyDefinedIn instance module Module(s) that define the instance. qyRefs instance, reference References to all symbol instances of the symbol, or, if the BOB is an instance, then the references to that particular instance itself. qyDefs instance, definition Definitions of all symbol instances of a symbol, or, if the BOB is an instance, then the definitions to that particular instance itself. qyBaseOf instance, instance, Instances that have class class the given symbol as their base class. qyDervOf instance, instance, Instances that are class class derived from the symbol. qyMembers instance, instance, All members of the class mem_var, given class mem_funct including bases. qyMemberOf instance, instance, All classes of which mem_var, class the given symbol is mem_func a member. qyImpMembers instance, instance, All members classb mem_var, implemented by the mem_funct given class. qyFriendIn instance, instance, All classes that class class give friend access to the given class. qyFriendOut instance, instance, All classes that class class obtain friend access from the given class. qyBaseSorted, -- -- Reserved for qyBaseIncSorted, internal use. qyDervSorted, qyDervIncSorted The result of a query is a collection of browser objects. To obtain the next browser object in the query information, use the following function: BOB BSC_API BobNext (VOID) Any one of the browser objects returned may be passed back to initiate another query. The name of the symbol for that browser object may be found using the function LszNameFrBob, which can also be used to obtain the next browser object in the collection. If there are no more browser objects left in the collection, the value bobNil is returned. ______________________________________________________________________ 3.3 Generating Name Overloads The GenerateOverloads and GenerateOverloadsEx functions find all possible browser objects that match a given name, such as all members of a given class, all class members having the given name, or all top-level items having the given name. These functions then pass each BOB to a given function (pointed to by PFN_BOB in GenerateOverloads and PFN_BOB_EX in GenerateOverloadsEx). WORD BSC_API GenerateOverloads (LSZ, MBF, PFN_BOB) WORD BSC_API GenerateOverloadsEx (LSZ, MBF, PFN_BOB_EX) The following are the forms LSZ can have and their subsequent action: class:: Generates a list of all members of the class. class::mem Generates a list of all members named mem. GenerateOverloadsEx also accepts wildcards, as in mem*, and nested classes (such as classA::classB::mem). mem Generates a list of all members mem in any class or top-level items. The member mem can be a regular member or it can be operator+, operator new, and so forth. GenerateOverloadsEx stops executing (returns) whenever the function pointed to by PFN_BOB_EX returns FALSE, whereas GenerateOverloads continues executing. This feature of GenerateOverloadsEx can be used, for example, to show the first n overloads in a list box without waiting for all the overloads to be computed. ______________________________________________________________________ 4 Browser Library Index This index lists all of the browser library functions, variables, and constants discussed in this reference document and also defined or declared in the header files BSC.H and BSCSUP.H, both of which provide the browser library interface. Each entry is followed by the section and/or table in which that particular item is discussed. B BadBSCVer() -- 2.1, T2 BaseInfo() -- 2.3.7 BaseRangeOfInst() -- 2.3.7 BobFrBase() -- 3.1 BobFrClsIdx() -- 3.1 BobFrDef() -- 3.1 BobFrDerv() -- 3.1 BobFrFrin() -- 3.1 BobFrFrout() -- 3.1 BobFrInst() -- 3.1 BobFrMod() -- 3.1 BobFrName() -- 3.1 BobFrRef() -- 3.1 BobFrSym() -- 3.1 BobFrUby() -- 3.1 BobFrUse() -- 3.1 BobNext() -- 3.2 bobNil -- 3.1 BSCClose() -- 2.1, T2 BSCFormat() -- 2.7, T8 BSCMaxSymLen() -- 2.8, T9 BSCOpen() -- 2.1, T2, 2.3.4, T7 BSCOutput() -- 2.1, T2, 2.3.4, T7 BSCPrintf() -- 2.7, T8 BSCRead() -- 2.1, T2 BSCSeek() -- 2.1, T2 BSCSprintf() -- 2.7, T8 C CallTreeInst () -- 2.4 CaseCmp() -- 2.7, T8 CaseCmpPrefix() -- 2.7, T8 ClassTreeInst () -- 2.4 CloseBSC() -- 2.2, T3 clsBase -- 3.1 clsDef -- 3.1 clsDerv -- 3.1 clsFrin -- 3.1 clsFrout -- 3.1 clsInst -- 3.1 clsMod -- 3.1 ClsOfBob() -- 3.1 clsRef -- 3.1 clsSym -- 3.1 clsUby -- 3.1 clsUse -- 3.1 D DefInfo() -- 2.3.5 DefRangeOfInst() -- 2.3.5 DervInfo() -- 2.3.7 DervRangeOfInst() -- 2.3.5 DumpInst() -- 2.3.4, T7 F FCallTreeLsz() -- 2.4 FCaseBSC() -- 2.8, T9 FClassTreeLsz() -- 2.4 FindPrefixRange () -- 3.1 FInstFilter () -- 2.3.4, T7 FOpenBSC () -- 2.2, T3 FormatDname () -- 2.7 T8 FOutlineModuleLsz ()-- 2.6 FreeLpv() -- 2.1, T2 FRevClassTreeLsz ()-- 2.4 FRevTreeLsz() -- 2.4 FrinInfo() -- 2.3.8 FrinRangeOfInst() -- 2.3.8 FroutInfo() -- 2.3.8 FroutRangeOfInst() -- 2.3.8 FWildMatch() -- 2.7, T8 G GenerateOverloads() -- 3.3 GenerateOverloadsEx() -- 3.3 I IbaseFrBob() -- 3.1 IdefFrBob() -- 3.1 IdervFrBob() -- 3.1 IfrinFrBob() -- 3.1 IfroutFrBob() -- 3.1 IinstContextFrIref() -- 2.3.4, T6 IinstFrBob() -- 3.1 IinstFrIref() -- 2.3.4, T6 IinstFrIdef() -- 2.3.4, T6 IinstMac() -- 2.3.4, T6 iinstNil -- 2.3.4, T6 IinstOfIms() -- 2.3.2, T5 IMODE_PRIVATE -- 2.3.4 IMODE_PROTECT -- 2.3.4 IMODE_PUBLIC -- 2.3.4 IMODE_VIRTUAL -- 2.3.4 ImodFrBob() -- 3.1 ImodFrLsz() -- 2.3.1, T4 ImodMac() -- 2.3.1, T4, 2.3.4, T6 imodNil -- 2.3.1, T4 InitBSCQuery () -- 3.2 INST_ATR_COMMON -- 2.3.4 INST_ATR_DECL_ONLY -- 2.3.4 INST_ATR_LOCAL -- 2.3.4 INST_ATR_MODULE -- 2.3.4 INST_ATR_NAMED -- 2.3.4 INST_ATR_NEAR -- 2.3.4 INST_ATR_PRIVATE -- 2.3.4 INST_ATR_PROTECT -- 2.3.4 INST_ATR_PUBLIC -- 2.3.4 INST_ATR_SHARED -- 2.3.4 INST_ATR_STATIC -- 2.3.4 INST_ATR_VIRTUAL -- 2.3.4 INST_TYP_CLASSNAM -- 2.3.4 INST_TYP_CONSTANT -- 2.3.4 INST_TYP_ENUMMEM -- 2.3.4 INST_TYP_ENUMNAM -- 2.3.4 INST_TYP_FUNCTION -- 2.3.4 INST_TYP_GROUP -- 2.3.4 INST_TYP_LABEL -- 2.3.4 INST_TYP_MACRO -- 2.3.4 INST_TYP_MEMFUNC -- 2.3.4 INST_TYP_MEMVAR -- 2.3.4 INST_TYP_PARAMETER-- 2.3.4 INST_TYP_PROGRAM -- 2.3.4 INST_TYP_SEGMENT -- 2.3.4 INST_TYP_STRUCNAM -- 2.3.4 INST_TYP_TYPEDEF -- 2.3.4 INST_TYP_UNIONNAM -- 2.3.4 INST_TYP_VARIABLE -- 2.3.4 InstInfo() -- 2.3.4, T6 InstRangeOfSym() -- 2.3.4, T6 IrefFrBob() -- 3.1 IsymFrBob() -- 3.1 IsymFrLsz() -- 2.3.3 IsymMac() -- 2.3.3, 2.3.4, T6 isymNil -- 2.3.3 IsymSupLsz() -- 2.3.3 IubyFrBob() -- 3.1 IuseFrBob() -- 3.1 L ListRefs () -- 2.5 LpvAllocCb() -- 2.1, T2 LszBaseName() -- 2.7, T8 LszBaseOfDname() -- 2.7, T8 LszClassOfDname() -- 2.7, T8 LszNameFrBob() -- 3.1 LszNameFrMod () -- 2.3.1, T4 LszNameFrSym () -- 2.3.3 LszTypInst() -- 2.3.4, T7 M MBF -- 2.3.4 mbfAll -- 2.3.4 mbfClass -- 2.3.4 mbfFuncs -- 2.3.4 mbfMacros -- 2.3.4 mbfNil -- 2.3.4 mbfTypes -- 2.3.4 mbfVars -- 2.3.4 MsRangeOfMod() -- 2.3.2, T5, 2.3.4, T6 O OutlineMod() -- 2.6 P PFN_BOB -- 3.3 PFN_BOB_EX -- 3.3 Q qyBaseIncSorted -- 3.2, T10 qyBaseOf -- 3.2, T10 qyBaseSorted -- 3.2, T10 qyCalledBy -- 3.2, T10 qyCalls -- 3.2, T10 qyContains -- 3.2, T10 qyDefinedIn -- 3.2, T10 qyDefs -- 3.2, T10 qyDervIncSorted -- 3.2, T10 qyDervOf -- 3.2, T10 qyDervSorted -- 3.2, T10 qyFiles -- 3.2,T10 qyFriendIn -- 3.2, T10 qyFriendOut -- 3.2, T10 qyImpMembers -- 3.2, T10 qyMemberOf -- 3.2, T10 qyMembers -- 3.2, T10 qyRefs -- 3.2, T10 qySymbols -- 3.2, T10 qyUsedBy -- 3.2, T10 qyUsedIn -- 3.2, T10 qyUses -- 3.2,T10 R ReadError() -- 2.1, T2 RefInfo() -- 2.3.5 RefRangeOfInst() -- 2.3.5 RevClassTreeInst ()-- 2.4 RevTreeInst () -- 2.4 S SeekError() -- 2.1, T2 SetCaseBSC() -- 2.7, T8, 2.8, T9 StatsBSC() -- 2.8, T9 U UbyInfo() -- 2.3.6 UbyRangeOfInst() -- 2.3.6 UseInfo() -- 2.3.6 UseRangeOfInst() -- 2.3.6